Constructing .help files

Description

I refer to archived HTML documents as '.help' files. I use lha to archive and unarchive components of HTML documents because its a good and readily available archiver. There are several GUI utilities available to make it easier to use, but they're not essential. The following points are essential to note:

• There should be a file called main.html or {document name}.html present. This file will be selected and displayed as the first page of the document
• There may be subdirectories, normally image subdirectories, but any number are permitted provided the HTML code correctly refers to HTML pages and images within those directories
• The archive can be called whatever you like as long as it ends in .help

Construction

The following describes how I manually create a .help file. A good way to start is to ensure that all the .html files are in a single directory. Ensure the only stuff in this directory are components of the .help file you wish to create. If your document has images, then an images or pics directory should be in that directory to contain these images. What we want to do is archive all these files into a single .help document.

Lets experiment on the Docs drawer of this archive. Copy this drawer to Ram: and enter the following commands from the shell:

cd Ram:Docs

lha a -xr Ram:GetHelp.help #?

This instructs lha to add the listed files to an archive called GetHelp.help in the Ram: directory. The '-x' option preserves the path of any files in subdirectories, ensuring that image links in the directory are still valid. The '-r' option collects files recursively and adds them to the '.help' file we have created.

If you're confident with this process, you should be able to replicate this process in any directory on your system and store the resultant archive in Help: rather than Ram: as in this example.

Making an Icon

I have included my default icon for '.help' files. I personally (still) use the DefIcons package with NewIcons, which is about as un-userfriendly as you can get.. I don't have any of the Workbench replacements, so any users with Scalos or Dopus Magellan can impliment as they see fit - let me know how that's done and I'll include it in the documentation. The filetype definition couldn't be simpler: .lha archives with a .help suffix are '.help' files.

NOTE: The default tool for this icon is OpenURL

NOTE: Your '.help' file must have a REAL .info file available if you wish to open a help file via a double-click in Workbench!!

Maintaining your own .help files

If you write HTML documents and which to exploit the concepts of the GetHelp system, remember that just because all the components of your document are in a '.help' file, it is no harder than before to modify individual images or HTML pages of your document. Remember, a '.help' document is simply an lha archive - files can be extracted singularly or entirely, deleted or replaced. Type lha from your shell to see the range of options available.

Storage

Please ensure your .help files are stored in a logical place. This can only make it easier trying to find them again, and for cross-referencing them from parent documents.